home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / GETSTR.HDR < prev    next >
Text File  |  1994-04-25  |  3KB  |  100 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _GetStr(cGetStr, nStrWidth, lMatchWidth, cPicture, nGRowMod, nGColMod,
  8. lUpper) --> cString
  9.  
  10. PARAMETERS:
  11.  
  12. cGetStr     : Character Prompt | Initial Value
  13. nStrWidth   : Maximum string length accepted
  14. lMatchWidth : Match nStrWidth to Length of cGetStr
  15. cPicture    : Picture string
  16. nGRowMod    : Row modification (added to default of 12)
  17. nGColMod    : Column modification
  18. lUpper      : Logical - force input to upper case if TRUE.
  19.  
  20. SHORT:
  21.  
  22. Prompt for and accept user character string input.
  23.  
  24. DESCRIPTION:
  25.  
  26. _GetStr() asks a question (passed as parameter) and returns the answer as
  27. a trimmed string.
  28.  
  29. cGetStr is the Prompt String.  If it contains a "|" (verticle bar)
  30. anywhere, the remainder of the string following the "|" becomes the
  31. initial value of the string.
  32.  
  33. _GetStr("Enter Your Name:",40)
  34.  
  35. In this example, there is no initial value.  The name must be typed,
  36. or nothing (blank) will be returned.
  37.  
  38. _GetStr("Enter Your Name:|Kirby",40)
  39.  
  40. In this example, the name will initially be "Kirby" and can be accepted
  41. by pressing enter.
  42.  
  43. _GetStr() is capable of accepting keyboard input without issueing a GET/READ.
  44. It can therefore be called while already in a read without disrupting that
  45. READ.
  46.  
  47. The entire prompt is centered in a box on the screen.  The default rows
  48. are 12-16.  The columns vary depending upon the length of cGetStr, which
  49. is centered on the screen.
  50.  
  51. nGRowMod and nGColMod are ADDED to these defaults and can be use to move
  52. the box off-center.  To move the box up or to the left, use negative values.
  53.  (I.e., nGColMod = -5, would cause the box to to be first centered, but
  54. then moved -5 Columns to the right (Adding negative numbers effectively
  55. causes a move to the LEFT, or 5 columns to the LEFT).
  56.  
  57. cPicture is a picture string to be used on the GET.
  58.  
  59. nStrWidth and lMatchWidth are mutually exclusive. If you pass nStrWidth the
  60. response string will be that length.  If you pass lMatchWidth == .t. then
  61. nStrWidth becomes ineffect, and the response string will match the length of
  62. the prompt string.
  63.  
  64. This is useful for ergonomics, but should not be used if you need to control
  65. the length of the response string (as when you are prompting for a file name
  66. where you need no more than eight characters.
  67.  
  68. In this case, pass nStrWidth == 8, and do not pass lMatchWidth, or pass it as
  69. .f.)
  70.  
  71. Box colors are white on red.
  72.  
  73. NOTE:
  74.  
  75. See also: _GetNum() which reads numerics, and possibly _Password()
  76. which receives a masked password.
  77.  
  78. EXAMPLE:
  79.  
  80. t = _GetStr('Enter Label of Hard Disk to Format',40)
  81. Result: t = 'WISE_DEV'
  82.  
  83. In this example, the maximum number of keystrokes that will be accepted is
  84. 40.
  85.  
  86. t = _GetStr('Enter Label of Hard Disk to Format',,TRUE)
  87.  
  88. In this example, the maximum number of keys that would be accepted is the
  89. width of the prompt string, i.e., 34.
  90.  
  91. cName = 'Kirby'
  92. t = GetStr("Enter Your Name:|"+cName)
  93.  
  94. In this case, the prompt will be "Enter Your Name:", and the intial value
  95. will be "Kirby" (derived from cName). Note that in this case, there is no
  96. string width specified. The string field will be the length of the prompt
  97. which happens to be 16 + 5 = 21 spaces.
  98.  
  99. ******************************************************************************/
  100.